Oracle Globalization Development Kit 10g Release 2 (10.2) README
======================================================================

What Is New In This Release?
----------------------------

Language and Character Set Detection (LCSD) enhancements
    The Language and Character Set Detection utility has been enhanced
    to also support the following:

    Input Stream Duplicator - The DualInputStreamBuilder class can be
    used when two independent stream operations are required for one
    InputStream source (e.g., one stream detects the language and
    character set and the other stream is for the real purpose). It
    generates two InputStream wrapper objects for one InputStream
    source.

    Streaming APIs - The LCSD stream and reader classes are available
    for performing additional operations on the input stream based on
    the detection result.

    Input Data Validation - The UTF-8 byte sequence may include
    invalid data that could compromise application security. The
    UTF8ValidationFilter class can be used to detect illegal UTF-8
    sequences before the JDK conversion takes place. When an illegal
    UTF-8 byte sequence is found, the filter can either raise an
    exception or replace with the replacement character.

Language and Character Set Detection of HTML contents
    Two GDK extended classes (LCSDetectionHTMLInputStream and
    LCSDetectionHTMLReader) are provided to support HTML input and
    discard HTML tags for better detection accuracy. For HTML input
    files, users can now get a precise detection on the input and
    verify the detection result. LCSD supports the HTML 4.01
    specification.

New GDK packaging
    The GDK Java library is now split into nine jar files for better
    class loading performance. Typically all jar files are installed
    under the same directory and only orai18n.jar needs to be included
    in the CLASSPATH. If that is not the case, then all nine jar files
    should be included in the CLASSPATH.


Installation
------------

GDK for Java consists of nine separate jar files which are shipped
with the Oracle database:

    - orai18n.jar
    - orai18n-mapping.jar
    - orai18n-utility.jar
    - orai18n-collation.jar
    - orai18n-translation.jar
    - orai18n-net.jar
    - orai18n-servlet.jar
    - orai18n-tools.jar
    - orai18n-lcsd.jar

If the application using the GDK is not hosted on the same machine
as the database, then the GDK files must be copied to the application
server and included into the CLASSPATH to run your application. You do
not need to install the Oracle database into your application server
to be able to run the GDK inside your Java application. GDK is a pure
Java library that runs on every platform. The Oracle client parameters
NLS_LANG and ORACLE_HOME are not required.

GDK applications can also be deployed in third-party J2EE compliant
application servers. Since the GDK framework for J2EE has a dependency
on the XML parser, if you encounter NoClassDefFoundError for classes
under oracle/xml/parser/v2/ when deploying in a non-Oracle environment,
you need to install the Oracle XML Parser (xmlparserv2.jar) of the same
release (as the GDK) in the deployment directory. This file is
downloadable from OTN as part of the Oracle XML Developers Kit (XDK) for
Java. This step is NOT required for deployment in an existing Oracle
environment, where both the Oracle database and Oracle Application Server
already include the XML parser.

Upgrade
-------

There is no special procedure required when upgrading from GDK 10.1 to
10.2. If all jar files are copied under the same directory, there is no
need to change the application classapath.


Known Problems/Limitations In This Release
------------------------------------------

The following is a list of known problems/limitations:

BUG-4085200 (OC4J class loading issue)
    Binding GDK applications throws NoClassDefFoundError for
    org/apache/regexp/RESyntaxException and loading application message
    bundles using OraResourceBundle.getBundle() throws
    MissingResourceException. This only happens with OC4J 10.1.2 and does
    not happen with 9.0.4. The solution is to take the following steps
    while deploying the application.

    a) Deploy the application
    $ java -jar admin.jar ormi://localhost/ admin <admin passwd> -deploy \
      -file <path>/gdkdemo.ear -deploymentName gdkdemo

    b) Uncomment the following line in
       $J2EE_HOME/application-deployments/gdkdemo/gdkdemo/orion-web.xml 

       <web-app-class-loader search-local-classes-first="true"
       include-war-manifest-class-path="true" />

    c) Bind the application
    $ java -jar admin.jar ormi://localhost/ admin <admin passwd> \
      -bindWebApp gdkdemo gdkdemo http-web-site /gdkdemo 

BUG-4115579 (user locale caching)
    This is a bug in the GDK shop demo. When switching between users using
    the drop-down menu in the demo, if the browser back button is used
    then the DBLocaleSource object of the previous user cached in the
    session is used instead. This type of caching will only work if the
    session is invalidated when users change (by logging out). This is
    fixed in the demo and the default caching policy for each type of
    locale source is described below: 

    oracle.i18n.servlet.localesource.DBLocaleSource

    This locale source will be cached in the session object by default.
    The caching is not based on user-id, hence it is suitable for
    applications where there is a single user per session (users login
    and logout), which is the most common scenario. 

    oracle.i18n.servlet.localesource.UserInput

    This locale source is not cached by default. Each request is
    processed to get the current user input locale.

    oracle.i18n.servlet.localesource.HttpAcceptLanguage 

    This locale source is not cached by default. Each request is
    processed to get the current locale setting. 

    oracle.i18n.servlet.localesource.ApplicationDefault

    This locale source is cached in the ApplicationContext. If the
    locale source changes (i.e. changes in the config file), the
    server has to be restarted.
